Creates, deletes, modifies and displays menus and menu items. Changes the tray icon and its tooltip. Controls whether the main window of a compiled script can be opened.
Menu, MenuName, Cmd [, P3, P4, P5]
| MenuName | It can be TRAY or the name of any custom menu. A custom menu is automatically created the first time its name is used with the Add command. For example: Menu, MyMenu, Add, Item1 Once created, a custom menu can be displayed with the Show command. It can also be attached as a submenu to one or more other menus via the Add command. |
| Cmd, P3, P4, P5 | These 4 parameters are dependent on each other. See list below for the allowed combinations. |
Add [, MenuItemName, Label-or-Submenu, Pn]: This is a multipurpose command that adds a menu item, updates one with a new submenu or label, or converts one from a normal item into a submenu (or vice versa). If MenuItemName does not yet exist, it will be added to the menu. Otherwise, MenuItemName is updated with the newly specified Label-or-Submenu.
To add a menu separator line, omit all three parameters.
The label subroutine is run as a new thread when the user selects the menu item (similar to Gosub and hotkey subroutines). If Label-or-Submenu is omitted, MenuItemName will be used as both the label and the menu item's name.
To have MenuItemName become a submenu -- which is a menu item that opens a new menu when selected -- specify for Label-or-Submenu a colon followed by the MenuName of an existing custom menu. For example:
Menu, MySubmenu, add, Item1 Menu, tray, add, This Menu Item Is A Submenu, :MySubmenu
The final parameter may contain the letter P followed by the menu's thread priority, e.g. P1. If this parameter is omitted when adding a menu item, the priority will be 0, which is the standard default. If omitted when updating a menu item, the item's priority will not be changed. To change an existing item's priority only, omit the Label-or-Submenu parameter. Use a decimal (not hexadecimal) number as the priority.
Delete [, MenuItemName]: Deletes MenuItemName from the menu. Standard menu items such as Exit (see below) cannot be individually deleted. If the default menu item is deleted, the effect will be similar to having used the NoDefault option. If MenuItemName is omitted, the entire MenuName menu will be deleted as will any menu items in other menus that use MenuName as a submenu.
DeleteAll: Deletes all custom menu items from the menu, leaving the menu empty unless it contains the standard items (see below). Unlike a menu entirely deleted by the Delete command (see above), an empty menu still exists and thus any other menus that use it as a submenu will retain those submenus.
Rename, MenuItemName [, NewName]: Changes MenuItemName to NewName (if NewName is blank, MenuItemName will be converted into a separator line). NewName must not be the same as any existing custom menu item. The menu item's current target label or submenu is unchanged.
Check, MenuItemName: Adds a visible checkmark in the menu next to MenuItemName (if there isn't one already).
Uncheck, MenuItemName: Removes the checkmark from MenuItemName if there is one.
ToggleCheck, MenuItemName: Adds a checkmark if there wasn't one; otherwise, removes it.
Enable, MenuItemName: Allows the user to once again select MenuItemName if was previously disabled (grayed).
Disable, MenuItemName: Changes MenuItemName to a gray color to indicate that the user cannot select it.
ToggleEnable, MenuItemName: Disables MenuItemName if it was previously enabled; otherwise, enables it.
Default [, MenuItemName]: Changes the menu's default item to be MenuItemName and makes that item's font bold (setting a default item in menus other than TRAY is currently purely cosmetic). When the user double-clicks the tray icon, its default menu item is launched. If there is no default, double-clicking has no effect. If MenuItemName is omitted, the effect is the same as having used NoDefault below.
NoDefault: For the tray menu: Changes the menu back to having its standard default menu item, which is OPEN for non-compiled scripts and none for compiled scripts (except when the MainWindow option is in effect). If the OPEN menu item does not exist due to a previous use of the NoStandard command below, there will be no default and thus double-clicking the tray icon will have no effect. For menus other than TRAY: Any existing default item is returned to a non-bold font.
Standard: Inserts the standard menu items at the bottom of the menu (if they are not already present). This command can be used with the tray menu or any other menu.
NoStandard: Removes all standard (non-custom) menu items from the tray menu (if they are present).
Icon [, FileName, IconNumber, 1]: Changes the script's icon to one of the ones from FileName. The following types of files are supported: ICO, CUR, ANI, EXE, DLL, CPL, SCR, and other types that contain icon resources. To use an icon group other than the first one in the file, specify its number for IconNumber (if omitted, it defaults to 1). For example, 2 would load the default icon from the second icon group. Specify an asterisk (*) for FileName to restore the script to its default icon.
The last parameter: Specify 1 for the last parameter to freeze the icon, or 0 to unfreeze it (or leave it blank to keep the frozen/unfrozen state unchanged). When the icon has been frozen, Pause and Suspend will not change it. Note: To freeze the current icon, use Menu, Tray, Icon,,, 1 ; (or 0 to unfreeze)
Changing the tray icon also changes the icon displayed by InputBox, Progress, and subsequently-created GUI windows. Compiled scripts are also affected even if a custom icon was specified at the time of compiling. Note: Changing the icon will not unhide the tray icon if it was previously hidden by means such as #NoTrayIcon; to do that, use Menu, Tray, Icon (with no parameters).
Slight distortion may occur when loading tray icons from file types other than .ICO. This is especially true for 16x16 icons. To prevent this, store the desired tray icon inside a .ICO file.
There are some icons built into the operating system's DLLs and CPLs that might be useful. For example: Menu, Tray, Icon, Shell32.dll, 174 ; Omits the DLL's path so that it works on Windows 9x too.
The built-in variables A_IconNumber and A_IconFile contain the number and name (with full path) of the current icon (both are blank if the icon is the default).
Icon (with no parameters): Creates the tray icon if it isn't already present. This will override #NoTrayIcon if that directive is also present in the script.
NoIcon: Removes the tray icon if it exists. If this command is used at the very top of the script, the tray icon might be briefly visible when the script is launched. To prevent that, use #NoTrayIcon instead. The built-in variable A_IconHidden contains 1 if the tray icon is currently hidden or 0 otherwise.
Tip [, Text]: Changes the tray icon's tooltip -- which is displayed when the mouse hovers over it. To create a multi-line tooltip, use the linefeed character (`n) in between each line, e.g. Line1`nLine2. Only the first 127 characters of Text are displayed. If Text is omitted, the tooltip is restored to its default text. The built-in variable A_IconTip contains the current text of the tooltip (blank if the text is at its default).
Show [, X, Y]: Displays MenuName, allowing the user to select an item with arrow keys, menu shortcuts (underlined letters), or the mouse. Any menu can be shown, including the tray menu but with the exception of GUI menu bars. If both X and Y are omitted, the menu is displayed at the current position of the mouse cursor. If only one of them is omitted, the mouse cursor's position will be used for it. X and Y are relative to the active window. Specify "CoordMode, Menu" beforehand to make them relative to the entire screen.
Color, ColorValue [, Single]: Changes the background color of the menu to ColorValue, which is one of the 16 primary HTML color names or a 6-digit RGB color value (see color chart). Leave ColorValue blank (or specify the word Default) to restore the menu to its default color. If the word Single is not present as the next parameter, any submenus attached to this menu will also be changed in color. This command has no effect on Windows 95/NT.
Click, ClickCount: Specify 1 for ClickCount to allow a single-click to activate the tray menu's default menu item. Specify 2 for ClickCount to return to the default behavior (double-click). For example: Menu, Tray, Click, 1
MainWindow: This command affects compiled scripts only. It allows the script's main window to be opened via the tray icon, which is otherwise impossible. It also enables the items in the main window's View menu -- such as "Lines most recently executed" -- allowing users to view the script's source code and other info. MenuName must be TRAY.
NoMainWindow (default): This command affects compiled scripts only. It restores the script to its default behavior, that is, it prevents the main window from being opened. Even while this option is in effect, the following commands are still able to show the main window when they are encountered in the script at runtime: ListLines, ListVars, ListHotkeys, and KeyHistory. MenuName must be TRAY.
UseErrorLevel [, off]: If this option is never used in the script, it defaults to OFF. The OFF setting displays a dialog and terminates the current thread whenever the Menu command generates an error. Specify Menu, Tray, UseErrorLevel to prevent the dialog and thread termination; instead, ErrorLevel will be set to 1 if there was a problem or 0 otherwise. To turn this option back off, specify OFF for the next parameter. This setting is global, meaning it affects all menus, not just MenuName.
To underline one of the letters in a menu item's name, precede that letter with an ampersand (&). When the menu is displayed, such an item can be selected by pressing the corresponding key on the keyboard. To display a literal ampersand, specify two consecutive ampersands as in this example: Save && Exit
The names of menus and menu items can be up to 260 characters long.
When referring to an existing menu or menu item, the name is not case sensitive but any ampersands must be included. For example: &Open
Separator lines can be added to the menu by using Menu, tray, add (i.e. omit all other parameters). However, separator lines currently cannot be individually deleted. To work around this, use Menu, tray, DeleteAll and then re-add your custom menu items.
New menu items are always added at the bottom of the menu. For the tray menu: To put your menu items on top of the standard menu items (after adding your own menu items) run Menu, tray, NoStandard followed by Menu, tray, Standard.
The standard menu items such as "Pause Script" and "Suspend Hotkeys" cannot be individually operated upon by any menu sub-command.
If a menu ever becomes completely empty -- such as by using Menu, MyMenu, DeleteAll -- it cannot be shown. If the tray menu becomes empty, right-clicking and double-clicking the tray icon will have no effect (in such cases it is usually better to use #NoTrayIcon).
If a menu item's subroutine is already running and the user selects the same menu item again, a new thread will be created to run that same subroutine, interrupting the previous thread. To instead buffer such events until later, use Critical as the subroutine's first line (however, this will also buffer/defer other threads such as the press of a hotkey).
Whenever a subroutine is launched via a menu item, it starts off fresh with the default values for settings such as SendMode. These defaults can be changed in the auto-execute section.
The built-in variables A_ThisMenuItem and A_ThisMenuItemPos contain the name and position of the custom menu item most recently selected by the user (blank if none). Similarly, A_ThisMenu is the name of the menu from which A_ThisMenuItem was selected. These variables are useful when building a menu whose contents are not always the same. In such a case, it is usually best to point all such menu items to the same label and have that label refer to the above variables to determine what action to take.
To keep a non-hotkey, non-GUI script running -- such as one that contains only custom menus or menu items -- use #Persistent.
GUI, Threads, Thread, Critical, #NoTrayIcon, Gosub, Return, SetTimer, #Persistent
; EXAMPLE #1: This is a working script that adds a new menu item to the bottom of the tray icon menu. #Persistent ; Keep the script running until the user exits it. Menu, tray, add ; Creates a separator line. Menu, tray, add, Item1, MenuHandler ; Creates a new menu item. return MenuHandler: MsgBox You selected %A_ThisMenuItem% from menu %A_ThisMenu%. return
; EXAMPLE #2: This is a working script that creates a popup menu that is displayed when the user presses the Win-Z hotkey. ; Create the popup menu by adding some items to it. Menu, MyMenu, Add, Item1, MenuHandler Menu, MyMenu, Add, Item2, MenuHandler Menu, MyMenu, Add ; Add a separator line. ; Create another menu destined to become a submenu of the above menu. Menu, Submenu1, Add, Item1, MenuHandler Menu, Submenu1, Add, Item2, MenuHandler ; Create a submenu in the first menu (a right-arrow indicator). When the user selects it, the second menu is displayed. Menu, MyMenu, Add, My Submenu, :Submenu1 Menu, MyMenu, Add ; Add a separator line below the submenu. Menu, MyMenu, Add, Item3, MenuHandler ; Add another menu item beneath the submenu. return ; End of script's auto-execute section. MenuHandler: MsgBox You selected %A_ThisMenuItem% from the menu %A_ThisMenu%. return #z::Menu, MyMenu, Show ; i.e. press the Win-Z hotkey to show the menu.
; EXAMPLE #3: This is a working script that demonstrates some of the various menu commands. #Persistent #SingleInstance menu, tray, add ; separator menu, tray, add, TestToggle&Check menu, tray, add, TestToggleEnable menu, tray, add, TestDefault menu, tray, add, TestStandard menu, tray, add, TestDelete menu, tray, add, TestDeleteAll menu, tray, add, TestRename menu, tray, add, Test return ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; TestToggle&Check: menu, tray, ToggleCheck, TestToggle&Check menu, tray, Enable, TestToggleEnable ; Also enables the next test since it can't undo the disabling of itself. menu, tray, add, TestDelete ; Similar to above. return TestToggleEnable: menu, tray, ToggleEnable, TestToggleEnable return TestDefault: if default = TestDefault { menu, tray, NoDefault default = } else { menu, tray, Default, TestDefault default = TestDefault } return TestStandard: if standard <> n { menu, tray, NoStandard standard = n } else { menu, tray, Standard standard = y } return TestDelete: menu, tray, delete, TestDelete return TestDeleteAll: menu, tray, DeleteAll return TestRename: if NewName <> renamed { OldName = TestRename NewName = renamed } else { OldName = renamed NewName = TestRename } menu, tray, rename, %OldName%, %NewName% return Test: MsgBox, You selected "%A_ThisMenuItem%" in menu "%A_ThisMenu%". return